home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / notify.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  9KB  |  283 lines
  1. /**
  2.  * @file notify.h Notification API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_NOTIFY_H_
  26. #define _GAIM_NOTIFY_H_
  27.  
  28. #include <stdlib.h>
  29. #include <glib-object.h>
  30. #include <glib.h>
  31.  
  32. #include "connection.h"
  33.  
  34. /**
  35.  * Notification types.
  36.  */
  37. typedef enum
  38. {
  39.     GAIM_NOTIFY_MESSAGE = 0, /**< Message notification.         */
  40.     GAIM_NOTIFY_EMAIL,       /**< Single e-mail notification.   */
  41.     GAIM_NOTIFY_EMAILS,      /**< Multiple e-mail notification. */
  42.     GAIM_NOTIFY_FORMATTED,   /**< Formatted text.               */
  43.     GAIM_NOTIFY_USERINFO,    /**< Formatted userinfo text.      */
  44.     GAIM_NOTIFY_URI          /**< URI notification or display.  */
  45.  
  46. } GaimNotifyType;
  47.  
  48. /**
  49.  * Notification message types.
  50.  */
  51. typedef enum
  52. {
  53.     GAIM_NOTIFY_MSG_ERROR   = 0, /**< Error notification.       */
  54.     GAIM_NOTIFY_MSG_WARNING,     /**< Warning notification.     */
  55.     GAIM_NOTIFY_MSG_INFO         /**< Information notification. */
  56.  
  57. } GaimNotifyMsgType;
  58.  
  59. /**
  60.  * Notification UI operations.
  61.  */
  62. typedef struct
  63. {
  64.     void *(*notify_message)(GaimNotifyMsgType type, const char *title,
  65.                             const char *primary, const char *secondary,
  66.                             GCallback cb, void *user_data);
  67.     void *(*notify_email)(const char *subject, const char *from,
  68.                           const char *to, const char *url,
  69.                           GCallback cb, void *user_data);
  70.     void *(*notify_emails)(size_t count, gboolean detailed,
  71.                            const char **subjects, const char **froms,
  72.                            const char **tos, const char **urls,
  73.                            GCallback cb, void *user_data);
  74.     void *(*notify_formatted)(const char *title, const char *primary,
  75.                               const char *secondary, const char *text,
  76.                               GCallback cb, void *user_data);
  77.     void *(*notify_userinfo)(GaimConnection *gc, const char *who,
  78.                               const char *title, const char *primary,
  79.                               const char *secondary, const char *text,
  80.                               GCallback cb, void *user_data);
  81.     void *(*notify_uri)(const char *uri);
  82.  
  83.     void (*close_notify)(GaimNotifyType type, void *ui_handle);
  84.  
  85. } GaimNotifyUiOps;
  86.  
  87.  
  88. #ifdef __cplusplus
  89. extern "C" {
  90. #endif
  91.  
  92. /**************************************************************************/
  93. /** @name Notification API                                                */
  94. /**************************************************************************/
  95. /*@{*/
  96.  
  97. /**
  98.  * Displays a notification message to the user.
  99.  *
  100.  * @param handle    The plugin or connection handle.
  101.  * @param type      The notification type.
  102.  * @param title     The title of the message.
  103.  * @param primary   The main point of the message.
  104.  * @param secondary The secondary information.
  105.  * @param cb        The callback to call when the user closes
  106.  *                  the notification.
  107.  * @param user_data The data to pass to the callback.
  108.  *
  109.  * @return A UI-specific handle.
  110.  */
  111. void *gaim_notify_message(void *handle, GaimNotifyMsgType type,
  112.                           const char *title, const char *primary,
  113.                           const char *secondary, GCallback cb,
  114.                           void *user_data);
  115.  
  116. /**
  117.  * Displays a single e-mail notification to the user.
  118.  *
  119.  * @param handle    The plugin or connection handle.
  120.  * @param subject   The subject of the e-mail.
  121.  * @param from      The from address.
  122.  * @param to        The destination address.
  123.  * @param url       The URL where the message can be read.
  124.  * @param cb        The callback to call when the user closes
  125.  *                  the notification.
  126.  * @param user_data The data to pass to the callback.
  127.  *
  128.  * @return A UI-specific handle.
  129.  */
  130. void *gaim_notify_email(void *handle, const char *subject,
  131.                         const char *from, const char *to,
  132.                         const char *url, GCallback cb,
  133.                         void *user_data);
  134.  
  135. /**
  136.  * Displays a notification for multiple e-mails to the user.
  137.  *
  138.  * @param handle    The plugin or connection handle.
  139.  * @param count     The number of e-mails.
  140.  * @param detailed  @c TRUE if there is information for each e-mail in the
  141.  *                  arrays.
  142.  * @param subjects  The array of subjects.
  143.  * @param froms     The array of from addresses.
  144.  * @param tos       The array of destination addresses.
  145.  * @param urls      The URLs where the messages can be read.
  146.  * @param cb        The callback to call when the user closes
  147.  *                  the notification.
  148.  * @param user_data The data to pass to the callback.
  149.  *
  150.  * @return A UI-specific handle.
  151.  */
  152. void *gaim_notify_emails(void *handle, size_t count, gboolean detailed,
  153.                          const char **subjects, const char **froms,
  154.                          const char **tos, const char **urls,
  155.                          GCallback cb, void *user_data);
  156.  
  157. /**
  158.  * Displays a notification with formatted text.
  159.  *
  160.  * The text is essentially a stripped-down format of HTML, the same that
  161.  * IMs may send.
  162.  *
  163.  * @param handle    The plugin or connection handle.
  164.  * @param title     The title of the message.
  165.  * @param primary   The main point of the message.
  166.  * @param secondary The secondary information.
  167.  * @param text      The formatted text.
  168.  * @param cb        The callback to call when the user closes
  169.  *                  the notification.
  170.  * @param user_data The data to pass to the callback.
  171.  *
  172.  * @return A UI-specific handle.
  173.  */
  174. void *gaim_notify_formatted(void *handle, const char *title,
  175.                             const char *primary, const char *secondary,
  176.                             const char *text, GCallback cb, void *user_data);
  177.  
  178. /**
  179.  * Displays user information with formatted text, passing information giving
  180.  * the connection and username from which the user information came.
  181.  *
  182.  * The text is essentially a stripped-down format of HTML, the same that
  183.  * IMs may send.
  184.  *
  185.  * @param gc        The GaimConnection handle associated with the information.
  186.  * @param who        The username associated with the information.
  187.  * @param title     The title of the message.
  188.  * @param primary   The main point of the message.
  189.  * @param secondary The secondary information.
  190.  * @param text      The formatted text.
  191.  * @param cb        The callback to call when the user closes
  192.  *                  the notification.
  193.  * @param user_data The data to pass to the callback.
  194.  *
  195.  * @return A UI-specific handle.
  196.  */
  197. void *gaim_notify_userinfo(GaimConnection *gc, const char *who,
  198.                            const char *title, const char *primary,
  199.                            const char *secondary, const char *text,
  200.                            GCallback cb, void *user_data);
  201.  
  202. /**
  203.  * Opens a URI or somehow presents it to the user.
  204.  *
  205.  * @param handle The plugin or connection handle.
  206.  * @param uri    The URI to display or go to.
  207.  *
  208.  * @return A UI-specific handle, if any. This may only be presented if
  209.  *         the UI code displays a dialog instead of a webpage, or something
  210.  *         similar.
  211.  */
  212. void *gaim_notify_uri(void *handle, const char *uri);
  213.  
  214. /**
  215.  * Closes a notification.
  216.  *
  217.  * This should be used only by the UI operation functions and part of the
  218.  * core.
  219.  *
  220.  * @param type      The notification type.
  221.  * @param ui_handle The notification UI handle.
  222.  */
  223. void gaim_notify_close(GaimNotifyType type, void *ui_handle);
  224.  
  225. /**
  226.  * Closes all notifications registered with the specified handle.
  227.  *
  228.  * @param handle The handle.
  229.  */
  230. void gaim_notify_close_with_handle(void *handle);
  231.  
  232. /**
  233.  * A wrapper for gaim_notify_message that displays an information message.
  234.  */
  235. #define gaim_notify_info(handle, title, primary, secondary) \
  236.     gaim_notify_message((handle), GAIM_NOTIFY_MSG_INFO, (title), \
  237.                         (primary), (secondary), NULL, NULL)
  238.  
  239. /**
  240.  * A wrapper for gaim_notify_message that displays a warning message.
  241.  */
  242. #define gaim_notify_warning(handle, title, primary, secondary) \
  243.     gaim_notify_message((handle), GAIM_NOTIFY_MSG_WARNING, (title), \
  244.                         (primary), (secondary), NULL, NULL)
  245.  
  246. /**
  247.  * A wrapper for gaim_notify_message that displays an error message.
  248.  */
  249. #define gaim_notify_error(handle, title, primary, secondary) \
  250.     gaim_notify_message((handle), GAIM_NOTIFY_MSG_ERROR, (title), \
  251.                         (primary), (secondary), NULL, NULL)
  252.  
  253. /*@}*/
  254.  
  255. /**************************************************************************/
  256. /** @name UI Operations API                                               */
  257. /**************************************************************************/
  258. /*@{*/
  259.  
  260. /**
  261.  * Sets the UI operations structure to be used when displaying a
  262.  * notification.
  263.  *
  264.  * @param ops The UI operations structure.
  265.  */
  266. void gaim_notify_set_ui_ops(GaimNotifyUiOps *ops);
  267.  
  268. /**
  269.  * Returns the UI operations structure to be used when displaying a
  270.  * notification.
  271.  *
  272.  * @return The UI operations structure.
  273.  */
  274. GaimNotifyUiOps *gaim_notify_get_ui_ops(void);
  275.  
  276. /*@}*/
  277.  
  278. #ifdef __cplusplus
  279. }
  280. #endif
  281.  
  282. #endif /* _GAIM_NOTIFY_H_ */
  283.